home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / djgpp / tktdoc / syslib.doc < prev    next >
Encoding:
Text File  |  1994-08-11  |  14.8 KB  |  625 lines
  1. THE DESQVIEW/X SYSTEM LIBRARY
  2.  
  3. The following functions are system-level calls that compose the non-BSD
  4. portion of the DESQview/X System Library.
  5.  
  6. General Functions:
  7.  
  8. dvpath - get the directory into which DESQview/X has been installed.
  9. CanonicalPath - calls DOS int 21 function 60h.
  10. pmiSegAbsolute - return a DOS extender independent first meg                                address.
  11. pmiSegCancel - cancel a protected mode selector.
  12. apiBeginC - begin critical region.
  13. apiEndC - end critical region .
  14. apiIsObj - determine if a given handle is valid.
  15. apiPause - give other tasks a chance to run.
  16.  
  17. Application Management Functions:
  18.  
  19. NewProc - start a new process .
  20. pif_open - open a program information file, using the dvp search
  21. path.
  22. pif_start - starts a process, using a filename as argument.
  23.  
  24. Directory Management Functions:
  25.  
  26. qopendir  - open a directory.
  27. qreaddir  - read a directory.
  28. qclosedir - close a directory.
  29.  
  30. Window Management Functions:
  31.  
  32. winMe     - get the current tasks window handle.
  33. winStream - write a stream to a window.
  34.  
  35. Mailbox Management Functions:
  36.  
  37. malFind   - find a mailbox by name .
  38. malName   - assign a global name to a mailbox..
  39. malSizeOf - get number of messages pending.
  40. malAddTo  - send a message by value with given status.
  41. malFree   - free a mailbox object.
  42. malNew    - create a new mailbox.
  43. malOpen   - open a mailbox.
  44. malNRead  - read a mailbox.
  45.  
  46. Object Management Functions:
  47.  
  48. obqClose    - close a tasks objectq .
  49. obqOpen     - open the tasks objectq.
  50. obqSizeOf   - get number of objectq entries pending.
  51. obqRead     - wait for any object to have input.
  52.  
  53. Timer Management Functions:
  54.  
  55. timAddTo    - start a timer for a given interval.
  56. timFree     - free a timer object.
  57. timNew      - create a timer object.
  58. timRead     - wait for a timer to expire.
  59.  
  60.  
  61.  
  62. General Functions
  63.  
  64. dvpath,
  65. get the directory into which DESQview/X has been installed.
  66.  
  67.  
  68. SYNOPSIS
  69.  
  70. #include <qdeck.h>
  71. void dvpath(char *dvxdir);
  72.  
  73. DESCRIPTION
  74.  
  75. Returns the directory into which DESQview/X has been installed.
  76.  
  77. dvxdir must be pre-allocated before dvpath is called.
  78.  
  79.  canonical Path
  80.  
  81. returns a canonical path
  82.  
  83. SYNOPSIS
  84.  
  85. #include <qdeck.h>
  86. int CanonicalPath(char *inpath, char *outpath);
  87.  
  88. DESCRIPTION
  89.  
  90. Calls DOS interrupt 21 function 60h to return a canonical path.
  91.  
  92.  pmiSegAbsolute
  93.  
  94. return a DOS extender independent real mode address
  95.  
  96. SYNOPSIS
  97.  
  98. #include .<pmi.h>
  99. char farptr pmiSegAbsolute(unsigned short seg, unsigned short offset,
  100.                            unsigned short len);
  101.  
  102. DESCRIPTION
  103.  
  104. This function returns a DOS extender independent real-mode address.
  105.  
  106.  
  107. For a 16-bit protected mode program this function creates a protected
  108. mode selector, with the segment limit set to 'len' bytes; a size of
  109. 0 represents 64K.
  110.  
  111. For a 32-bit protected mode program this function maps an address
  112. to the first Megabyte selector.
  113.  
  114. This function is necessary when copying data from protected mode to
  115. real mode. It should be used in conjunction with pmiSegCancel();
  116.  
  117.  pmiSegCancel
  118.  
  119. cancel a protected mode selector
  120.  
  121. SYNOPSIS
  122.  
  123. #include <pmi.h>
  124. void pmiSegCancel(void farptr);
  125.  
  126. DESCRIPTION
  127.  
  128. This function cancels a protected mode pointer.  The memory is not
  129. freed or released; the selector is merely made invalid.
  130.  
  131.  apiBeginC
  132.  
  133. begin critical region
  134.  
  135. SYNOPSIS
  136.  
  137. #include <dvapie.h>
  138. void apiBeginC(void);
  139.  
  140. DESCRIPTION
  141.  
  142. The apiBeginC function causes the current task to enter a critical
  143. region during which all multitasking is suspended.  The calling task
  144. is allowed to continue execution until it calls apiEndc or voluntarily
  145. gives up control. If it voluntarily gives up control  (by waiting
  146. for keyboard input for instance) multitasking is allowed to resume
  147. until the task regains control, at which time multitasking is again
  148. suspended. This facility can be useful for executing time critical
  149. sections of code and for controlling access to common resources. It
  150. should be used sparingly to avoid degrading overall system performance.
  151.  
  152. If another task is using DOS when the apiBeginC call is made, the
  153. caller will be suspended until DOS is free. This means that you are
  154. free to call DOS from inside a critical region.
  155.  
  156.  apiEndC
  157.  
  158. end critical region
  159.  
  160. SYNOPSIS
  161.  
  162. #include <dvapie.h>
  163. void apiEndC(void);
  164.  
  165. DESCRIPTION
  166.  
  167. The apiEndC function defines the end of a critical region of code.
  168. Critical regions are entered via the apiBeginC function. Calls to
  169. apiBeginC and apiEndC may be nested. Multitasking does not resume
  170. until an apiEndC call has been executed for every apiBeginC call that
  171. has been made.
  172.  
  173.  apiIsObj
  174.  
  175. determine if a given handle is valid
  176.  
  177. SYNOPSIS
  178.  
  179. #include <dvapie.h>
  180. int apiIsObj(unsigned long objhan);
  181. /* returns: 1 if valid handle, 0 otherwise */
  182.  
  183. DESCRIPTION
  184.  
  185. The apilsObj function returns 1 if the value specified is the handle
  186. of a currently valid object.  Otherwise, it returns 0. It is generally
  187. better to keep track of your  own objects rather than depend on this
  188. call. It can help, however,  in error paths where bookkeeping can
  189. be difficult.
  190.  
  191.  apiPause
  192.  
  193. give other tasks a chance to run
  194.  
  195. SYNOPSIS
  196.  
  197. #include <dvapie.h>
  198. void apiPause(void);
  199.  
  200. DESCRIPTION
  201.  
  202. The apiPause function gives up control to the dispatcher so that other
  203. tasks can be run. The calling task will regain control when its normal
  204. turn  occurs. Applications should make this call within all busy-wait
  205. loops,  that is, loops that are doing nothing useful but looking for
  206. something  to do.
  207.  
  208. Application Management Functions
  209.  
  210.  NewProc
  211.  
  212. start a new process
  213.  
  214. SYNOPSIS
  215.  
  216. #include <qdeck.h>
  217. unsigned long NewProc(char *dvpbuf,int len);
  218.  
  219. DESCRIPTION
  220.  
  221. Creates a new DESQview/X process. dvpbuf is a dvp either previously
  222. read from disk or one created in memory. len is the length of the
  223. dvp being passed in dvpbuf.
  224.  
  225. Allows a task to start a new process, just as if the user had selected  it
  226. from the window manager menu. dvpbuf is a dvp either previously read
  227. from disk or one created in memory. len is the length of the dvp being
  228. passed in dvpbuf.
  229.  
  230. NewProc returns the handle of the new process' initial task to the
  231. caller.
  232.  
  233.  pif_open
  234.  
  235. open a program information file, using the dvp search
  236. path.
  237.  
  238. SYNOPSIS
  239.  
  240. #include <qdeck.h>
  241. FILE *pif_open(char *pifname, const char **pathname);
  242.  
  243. DESCRIPTION
  244.  
  245. Opens a dvp program information file, given a pathname. You may want
  246. to use pif_open in conjunction with fread() and NewProc() if adjustments
  247. need to be made to the dvp before it is started.
  248.  
  249. Returns a file handle on success or NULL on failure.
  250.  
  251.  pif_start
  252.  
  253. starts a process, using a filename as argument.
  254.  
  255. SYNOPSIS
  256.  
  257. #include <qdeck.h>
  258. int pif_start(char *args);
  259.  
  260. DESCRIPTION
  261.  
  262. Starts a process, using a filename as argument. The first word of
  263. args must be a file name. If no extension is present a .dvp will be
  264. added. If no path is present the file will be looked for in current
  265. directory then in the path.
  266.  
  267. Returns 0 on success, ENOENT if the file specified by args is not
  268. found, EBADF if the file specified by args is invalid, E2BIG if the
  269. dvp in the file specified by args is an invalid length and ENOEXEC
  270. if the new process cannot be started.
  271.  
  272. Directory Management Functions
  273.  
  274. These functions are an alternative to the analogous native compilers
  275. functions.
  276.  
  277.  qopendir
  278.  
  279. open a directory
  280.  
  281. SYNOPSIS
  282.  
  283. #include <qdirent.h>
  284. qDIR *qopendir(char *dirname);
  285.  
  286. DESCRIPTION
  287.  
  288. qopendir opens the directory named by filename and associates a directory
  289. stream with it.  qopendir returns a pointer to be used to identify
  290. the directory stream in subsequent operations. The pointer NULL is
  291. returned if filename cannot be accessed or is not a directory, or
  292. if it cannot malloc enough memory to hold a DIR structure or a buffer
  293. for the directory entries.
  294.  
  295.  qreaddir
  296.  
  297. read a directory
  298.  
  299. SYNOPSIS
  300.  
  301. #include <qdirent.h>
  302. struct qdirent *qreaddir(qDIR *dp);
  303.  
  304. DESCRIPTION
  305.  
  306. qreaddir returns a pointer to the next active directory entry. No
  307. inactive  entries are returned. It returns NULL upon reaching the
  308. end of the  directory or upon detecting an invalid location in the
  309. directory.
  310.  
  311.  qclosedir
  312.  
  313. close a directory
  314.  
  315. SYNOPSIS
  316.  
  317. #include <qdirent.h>
  318. int     qclosedir(qDIR *dp);
  319.  
  320. DESCRIPTION
  321.  
  322. qclosedir closes the named directory stream and frees the qDIR structure.
  323.  
  324.  
  325. Window Management Functions
  326.  
  327.  winMe
  328.  
  329. get the current tasks window handle
  330.  
  331. SYNOPSIS
  332.  
  333. #include <dvapie.h>
  334. unsigned long winMe(void);
  335.  
  336. DESCRIPTION
  337.  
  338. The winMe function returns the handle of the current task's window.
  339.  
  340.  winStream
  341.  
  342.  write a stream to a window
  343.  
  344. SYNOPSIS
  345.  
  346. #include <dvapie.h>
  347. unsigned long winStream(unsigned long winhan, char * stream);
  348.  
  349. DESCRIPTION
  350.  
  351. The winStream function sends a data stream to a window. Returns a
  352. new window handle or 0, given a window handle and a pointer to a stream
  353. to be written.  winStream cannot be used to define a field table entry
  354.  
  355. Mailbox Management Functions
  356.  
  357.  malFind
  358.  
  359. - find a mailbox by name
  360.  
  361. SYNOPSIS
  362.  
  363. #include <dvapie.h>
  364. unsigned long malfind (char *name, int lname);
  365. /* char *name; pointer to name string */
  366. /* int  lname; length of name string */
  367.  
  368. The malFind function searches for a mailbox with the given name and
  369. returns its  handle, or zero if no mailbox has that name.
  370.  
  371.  malName
  372.  
  373. - assign a global name to a mailbox
  374.  
  375. SYNOPSIS
  376.  
  377. #include <dvapie.h>
  378. void malName(unsigned long malhan,char *name,int lname);
  379. /* unsigned long  malhan;  mailbox handle */
  380. /* char     *name; pointer to name string */
  381. /* int       lname;  length of name string */
  382.  
  383. DESCRIPTION
  384.  
  385. The malName function assigns a name to a mailbox. Once a mailbox has
  386. been named, other tasks can determine its handle by calling the malFind
  387. function.
  388.  
  389.  malSizeOf
  390.  
  391. get number of messages pending
  392.  
  393. SYNOPSIS
  394.  
  395. #include <dvapie.h>
  396. int malSizeOf(unsigned long malhan, int *len);
  397. /* mailbox handle */
  398.  
  399. DESCRIPTION
  400.  
  401. Returns the number of messages currently queued to the mailbox.
  402.  
  403.  malAddTo
  404.  
  405. - send a message with given status.
  406.  
  407. SYNOPSIS
  408.  
  409. #include <dvapie.h>
  410. int malAddto (unsigned long malhan,char *buffer,int buflen,
  411.               int status,  int append);
  412. /* unsigned long malhan; mailbox handle */
  413. /* char *buffer; pointer to message */
  414. /* int buflen; length of message */
  415. /* int status; status of message */
  416. /* int apend; whether to append messages or not */
  417.  
  418. DESCRIPTION
  419.  
  420. The malAddto function sends a message by value and explicitly sets
  421. the message status. If append is TRUE, messages of the same status
  422. can be appended and read as a stream. The status value is supplied
  423. by the sender and is an arbitrary value in the range 0 to 255.
  424.  
  425. Returns zero on success or non-zero on failure.
  426.  
  427.  malFree
  428.  
  429. free a mailbox object
  430.  
  431. SYNOPSIS
  432.  
  433. #include <dvapie.h>
  434. void malFree(unsigned long malhan);
  435. /* unsigned long malhan; mailbox handle */
  436.  
  437. DESCRIPTION
  438.  
  439. The malFree function frees all memory associated with the mailbox
  440. including any messages still queued to the mailbox.
  441.  
  442.  malNew
  443.  
  444. create a new mailbox
  445.  
  446. SYNOPSIS
  447.  
  448. #include <dvapie.h>
  449. int  malNew(unsigned long malhan);
  450. /* unsigned long malhan; mailbox handle */
  451.  
  452. DESCRIPTION
  453.  
  454. The malNew function creates a new mailbox object and returns its handle.
  455.  
  456.  
  457.  malOpen
  458.  
  459. open a mailbox
  460.  
  461. SYNOPSIS
  462.  
  463. #include <dvapie.h>
  464. void malOpen(unsigned long malhan);
  465. /* unsigned long malhan; mailbox handle */
  466.  
  467. DESCRIPTION
  468.  
  469. The malOpen function opens a mailbox for input. It establishes the
  470. calling task as the owner of the mailbox and, therefore, as the only
  471. task allowed to read the mailbox. You must open a mailbox that you
  472. have created before any task can send messages to it. Your task mailbox
  473. is opened automatically for you by DESQview/X.
  474.  
  475.  malNRead
  476.  
  477. read a mailbox
  478.  
  479. SYNOPSIS
  480.  
  481. #include <dvapie.h>
  482.  
  483. int malNRead(unsigned long malhan, char *buffer, int *len, int *stat);
  484. /* unsigned long malhan; mailbox handle */
  485. /* char *buffer; pointer to data read */
  486. /* int *len; returns: pointer to length of message*/
  487. /* int *stat; returns: pointer to status value to associate with  message */
  488.  
  489. DESCRIPTION
  490.  
  491. The malNRead function returns the next message queued to the specified
  492. mailbox and its status. The length of the message is passed to the
  493. function with the requested length and returns the actual length read.
  494. When  you read a mailbox that is not already open DESQview/X will
  495. open it for you.
  496.  
  497. Returns zero on success and non-zero on failure.
  498.  
  499. Object Management Functions
  500.  
  501.  obqClose
  502.  
  503. close a tasks objectq
  504.  
  505. SYNOPSIS
  506.  
  507. #include <dvapie.h>
  508. unsigned long obqClose(void);
  509.  
  510. DESCRIPTION
  511.  
  512. The obqClose function discards all objects from the task's objectq
  513. and prevents any further objects from being added. Each object in
  514. the objectq is erased to insure that its data is also discarded. The
  515. objects remain open.
  516.  
  517.  obqOpen
  518.  
  519. open the tasks objectq
  520.  
  521. SYNOPSIS
  522.  
  523. #include <dvapie.h>
  524. void obqOpen(void);
  525.  
  526. DESCRIPTION
  527.  
  528. The obqOpen function opens the task's objectq for use.
  529.  
  530.  obqSizeOf
  531.  
  532. get number of objectq entries pending
  533.  
  534. SYNOPSIS
  535.  
  536. #include <dvapie.h>
  537. int  obqSizeOf (void);
  538.  
  539. DESCRIPTION
  540.  
  541. The obqSizeof function returns the number of objects in the calling
  542. task's objectq.
  543.  
  544.  obqRead
  545.  
  546. wait for any object to have input
  547.  
  548. SYNOPSIS
  549.  
  550. #include <dvapie.h>
  551. unsigned long obqRead (void);
  552.  
  553. DESCRIPTION
  554.  
  555. The obqRead function returns the object handle of the next object
  556. in the objectq. ObqRead of an empty objectq suspends the calling task
  557. until an object is added to the queue. The obqRead function automatically
  558. opens the objectq if it was not previously open.
  559.  
  560. Timer Management Functions
  561.  
  562.  timAddTo
  563.  
  564. start a timer for a given interval
  565.  
  566. SYNOPSIS
  567.  
  568. #include <dvapie.h>
  569. void timAddto (unsigned long timhan,unsigned long interval);
  570. /* unsigned long timhan;  timer handle */
  571. /* unsigned long interval; # 1/100ths of a second in the time interval  */
  572.  
  573. DESCRIPTION
  574.  
  575. The timAddto function starts a timer running that will expire after
  576. a specified time interval. The duration of the timer is defined by
  577. a 32-bit number that represents the number of 1/100ths of a second
  578. in the interval. The timer is automatically opened if  necessary.
  579.  
  580.  timFree
  581.  
  582. free a timer object
  583.  
  584. SYNOPSIS
  585.  
  586. #include <dvapie.h>
  587. void timFree (unsigned long timhan);
  588. /* unsigned long timhan;  timer handle */
  589.  
  590. DESCRIPTION
  591.  
  592. The timFree function closes a timer if it is still open and frees
  593. the memory associated with the timer object.
  594.  
  595.  timNew
  596.  
  597. create a timer object
  598.  
  599. SYNOPSIS
  600.  
  601. #iinclde <dvapie.h>
  602. unsigned long timNew (unsigned long *timer);
  603.  
  604. DESCRIPTION
  605.  
  606. The timNew function creates a new timer object and returns its handle.
  607.  
  608.  
  609.  timRead
  610.  
  611.  wait for a timer to expire
  612.  
  613. SYNOPSIS
  614.  
  615. #include <dvapie.h>
  616. unsigned long timRead (unsigned long *timer);
  617.  
  618. DESCRIPTION
  619.  
  620. The timRead function suspends the calling task until the specified
  621. timer expires. The return parameter indicates the time-of-day that
  622. the timer expired, represented as a 32-bit count of the number of
  623. 1/100ths of a second since midnight.
  624.  
  625.